`co(4,7);───────────────────────── /// The InTUItion Library ──────────────────────────`co();

		The InTUItion library is a small set of macros and functions that allow
	you to use the TUI files created with the construction program.  Very few
	library functions are normally needed by the programmer as InTUItion does
	most of the work for you.  There are a number of undocumented functions
	used internally by InTUItion: if you are a real "power programmer" you may
	wish to examine the source code and see how things are done.

               `keyword(InTUItion Macros,/// InTUItion Macros);     `keyword(InTUItion Functions,/// InTUItion Functions);

`co(4,7);──────────────────────────── /// InTUItion Macros ────────────────────────────`co();

	NOTE: All object's x and y coordinates are offsets from the dialog's
				upper-left hand corner.  Therefore, if you move a dialog with
				position_dialog or center_dialog, no other adjustments are required.
				Furthermore, you can adjust a dialog's parameters on the fly to
				alter its shape, size, appearance, etc.  EnQue's Hypertext Help
				Engine does this depending on its size.  The "get" macros below can
				be used on both sides of a "C" expression. For instance:

				`co(15,?);tmp = get_sldr_pos(&Work_tui, H_SLIDER);
        get_sldr_pos(&Work_tui, H_SLIDER) = 124L;`co();

	`co(15,?);get_dlg_wnp(tp, i)`co();    - gets the dialog's window pointer.
	`co(15,?);get_item_type(tp, i)`co();  - gets an object's type (BUTTON, SLIDER, etc).
	`co(15,?);get_item_x(tp, i)`co();     - gets an object's x offset.
	`co(15,?);get_item_y(tp, i)`co();     - gets an object's y offset.
	`co(15,?);get_item_w(tp, i)`co();     - gets an object's width.
	`co(15,?);get_item_h(tp, i)`co();     - gets an object's heigth.
	`co(15,?);get_box_att(tp, i)`co();    - gets a box's normal attribute.
	`co(15,?);get_sldr_pos(tp, i)`co();   - gets a slider's current position.
	`co(15,?);get_str_text(tp, i)`co();   - gets a pointer to a text string's text.
	`co(15,?);get_btn_text(tp, i)`co();   - gets a pointer to a button's text.
	`co(15,?);get_btn_att(tp, i)`co();    - gets a button's normal color attribute.
	`co(15,?);get_check_text(tp, i)`co(); - gets a pointer to a check box's text.
	`co(15,?);get_inp_text(tp, i)`co();   - gets a pointer to an input's text.
	`co(15,?);get_inp_mask(tp, i)`co();   - gets a pointer to an input's mask.
	`co(15,?);get_inp_tplt(tp, i)`co();   - gets a pointer to an input's template.

	`co(15,?);set_btn_text(tp,i,s)`co();     - sets a button's text, reallocating if necessary.
	`co(15,?);set_str_text(tp,i,s)`co();     - sets a string's text, reallocating if necessary.
	`co(15,?);set_inp_strs(tp,i,t,m,p)`co(); - sets an input's text, mask, and template,
	                           reallocating if necessary.

	`co(15,?);is_valid_inx(tp, i)`co();   - returns 1 if "i" is a valid TUI index.
	`co(15,?);is_selected(tp, i)`co();    - returns 1 if the object "i" is currently selected.
	`co(15,?);is_tabbed(tp, i)`co();      - returns 1 if the object "i" is currently tabbed.

	`co(15,?);select(tp, i)`co();         - selects the object "i".
	`co(15,?);deselect(tp, i)`co();       - deselects the object "i".
	`co(15,?);tab(tp, i)`co();            - tabs to the object "i".
	`co(15,?);detab(tp, i)`co();          - detabs the object "i".

`co(4,7);─────────────────────────── /// InTUItion Functions ──────────────────────────`co();

		InTUItion is comprised of many functions.  Few, however, need to be used
	by the programmer.  By design, InTUItion does all of the grunt work,
	freeing you for more important matters.  Listed below are the InTUItion
	functions.  Learning just these few will give you full control over
	InTUItion!

	`keyword(A) base_at_cr,/// base_at_cr);
	`keyword(B) draw_item,/// draw_item);
	`keyword(C) refresh_dialog,/// refresh_dialog);
	`keyword(D) draw_dialog,/// draw_dialog);
	`keyword(E) erase_dialog,/// erase_dialog);
	`keyword(F) center_dialog,/// center_dialog);
	`keyword(G) position_dialog,/// position_dialog);
	`keyword(H) do_dialog,/// do_dialog);
	`keyword(I) load_tui,/// load_tui);
	`keyword(J) save_tui,/// save_tui);
	`keyword(K) init_tui,/// init_tui);
	`keyword(L) register_xxxx_tui,/// register_xxxx_tui);
	`keyword(M) end_tui,/// end_tui);
	`keyword(N) free_tui,/// free_tui);
	`keyword(O) set_slider,/// set_slider);
	`keyword(P) file_selected,/// file_selected);
	`keyword(Q) tui_help,/// tui_help);


`co(15,?);/// base_at_cr`co();   `keyword(source,[T_BASE.C]~base_at_cr);
	  Looks for an object under the specified column and row within a dialog
	box.  This is useful where you have buttons in a dialog and need to find
	which button is located at a specific column and row.  This routine is
	used internally by InTUItion.

Prototype:
	int base_at_cr( TUI *tuip, int inx, int col, int row );

Parameters:
`co(11,?);  TUI *tuip`co();
    A pointer to a TUI structure.                             
`co(11,?);  int  inx`co();
    The index for the dialog box in question.
`co(11,?);  int  col`co();
    The column in question.
`co(11,?);  int  row`co();
    The row in question.

Usage:
  int inx;
  TUI tui, TUI *tuip = &tui;
  
  inx = base_at_cr(tuip, 0, 10, 14);  /* find object that 10,14 is within */

`co(15,?);/// draw_item`co();   `keyword(source,[T_DLG.C]~draw_item);
	  Draws the TUI object indexed by "inx".   Call this to redraw an item
	when needed, such as after changing its position or attribute.

Prototype:
	int draw_item( TUI *tuip, int inx );

Parameters:
`co(11,?);  TUI *tuip`co();
    A pointer to a TUI structure.                             
`co(11,?);  int  inx`co();
    The index into the TUI for this object. (Use #define name).

Usage:
  int inx;
  TUI tui, TUI *tuip = &tui;
  
  inx = draw_item(tuip, OK_BUTTON);

`co(15,?);/// refresh_dialog`co();   `keyword(source,[T_DLG.C]~refresh_dialog);
	  Redraws all dialog objects and might be used where several items are
	modified and you don't wish to call draw_item for each.  This routine does
	not clear the dialog first; to do this if needed, get the dialog window
	pointer and call wn_clear.

Prototype:
	int refresh_dialog( TUI *tuip, int inx );

Parameters:
`co(11,?);  TUI *tuip`co();
    A pointer to a TUI structure.                             
`co(11,?);  int  inx`co();
    The index into the TUI for this dialog object. (Use #define name).

Usage:
  TUI tui, TUI *tuip = &tui;
  
  /* modify button attributes */
  refresh_dialog(tuip, HELP_DLG);


`co(15,?);/// draw_dialog`co();   `keyword(source,[T_DLG.C]~draw_dialog);
  	Draws the dialog on the screen, allocating space for the window and
	adding it to the UltraWin Window Manager linked list (if used). Do not
	call this routine more than once without calling `keyword(erase_dialog,///erase_dialog);.  To
	redraw a dialog that has been drawn but overwritten, call `keyword(refresh_dialog,/// refresh_dialog);.

Prototype:
	int draw_dialog( TUI *tuip, int inx );

Parameters:
`co(11,?);  TUI *tuip`co();
    A pointer to a TUI structure.                             
`co(11,?);  int  inx`co();
    The index into the TUI for this dialog object. (Use #define name).

Usage:
  TUI tui, TUI *tuip = &tui;
  
  draw_dialog(tuip, HELP_DLG);
  erase_dialog(tuip, HELP_DPG);

`co(15,?);/// erase_dialog`co();   `keyword(source,[T_DLG.C]~erase_dialog);
	  Erases a dialog drawn on the screen, freeing any space that was
	allocated and removing the window from the UltraWin window manager linked
	list (if used).  Do not call this routine more than once without calling
	`keyword(draw_dialog,/// draw_dialog);.

Prototype:
	int erase_dialog( TUI *tuip, int inx );

Parameters:
`co(11,?);  TUI *tuip`co();
    A pointer to a TUI structure.                             
`co(11,?);  int  inx`co();
    The index into the TUI for this dialog object. (Use #define name).

Usage:
  TUI tui, TUI *tuip = &tui;
  
  draw_dialog(tuip, HELP_DLG);
  erase_dialog(tuip, HELP_DPG);

`co(15,?);/// center_dialog`co();   `keyword(source,[T_DLG.C]~center_dialog);
	  Centers a dialog on the screen.  Note that this routine does not
	actually redraw the dialog, it merely changes the position; hence it
	should be called before `keyword(draw_dialog,/// draw_dialog);.

Prototype:
	int center_dialog( TUI *tuip, int inx );

Parameters:
`co(11,?);  TUI *tuip`co();
    A pointer to a TUI structure.                             
`co(11,?);  int  inx`co();
    The index into the TUI for this dialog object. (Use #define name).

Usage:
  TUI tui, TUI *tuip = &tui;
  
  center_dialog(tuip, HELP_DLG);
  draw_dialog(tuip, HELP_DLG);
  erase_dialog(tuip, HELP_DPG);

`co(15,?);/// position_dialog`co();   `keyword(source,[T_DLG.C]~position_dialog);
	  Positions a dialog on the screen at a given column and row.  Note that
	this routine does not actually redraw the dialog, it merely changes the
	position.  Like `keyword(center_dialog,/// center_dialog);, this function should be called
	before drawing the dialog on the screen with `keyword(draw_dialog,/// draw_dialog);.

Prototype:
	int position_dialog( TUI *tuip, int inx, int col, int row );

Parameters:
`co(11,?);  TUI *tuip`co();
    A pointer to a TUI structure.                             
`co(11,?);  int  inx`co();
    The index into the TUI for this dialog object. (Use #define name).
`co(11,?);  int  col`co();
    The new column position.
`co(11,?);  int  row`co();
    The new row position.

Usage:
  TUI tui, TUI *tuip = &tui;
  
  position_dialog(tuip, HELP_DLG, 10, 7);
  draw_dialog(tuip, HELP_DLG);
  erase_dialog(tuip, HELP_DPG);

`co(15,?);/// do_dialog`co();   `keyword(source,[T_DLG.C]~do_dialog);
	  This is the core function of InTUItion.  Very few other functions will
	ever be used.  This is a testament to the simplicity of interfacing to
	InTUItion.  This routine handles the users interaction with the dialog and
	returns the index of the object selected, modified, entered, etc.

Prototype:
	int do_dialog( TUI *tuip, int inx, int mode );

Parameters:
`co(11,?);  TUI *tuip`co();
    A pointer to a TUI structure.                             
`co(11,?);  int  inx`co();
    The index into the TUI for this dialog object. (Use #define name).
`co(11,?);  int  mode`co();
    This is a very important parameter.  It's the key to making the
    do_dialog function do exactly what you need and nothing more.  You may
    use the following (defined in T.H):
    `co(15,?);DO_NORMAL`co();       - returns control only after a user selects a dialog
                      object that has been set as an exit, or ESC has been
                      pressed, or the mouse has been clicked off of the
                      dialog box.  This bit makes the usage of inputs modal,
                      in that you must tab or cursor to the input, press
                      <Enter>, type the input and press <Enter> to accept.

    `co(15,?);DO_RETURN_EVENT`co(); - returns when the user enters a key or mouse event
                      that the dialog routine does not process.
    `co(15,?);DO_RETURN_TAB`co();    - returns when the Tab key is pressed.
    `co(15,?);DO_RETURN_ENTER`co();  - returns when the Enter key is pressed.
    `co(15,?);DO_RETURN_LEFT`co();  - returns when the left cursor key is pressed.
    `co(15,?);DO_RETURN_RIGHT`co();  - returns when the right cursor key is pressed.
    `co(15,?);DO_RETURN_UP`co();    - returns when the up cursor key is pressed.
    `co(15,?);DO_RETURN_DOWN`co();  - returns when the down cursor key is pressed.
    `co(15,?);DO_RETURN_ARROW`co(); - returns when a user presses any arrow cursor key.
    `co(15,?);DO_RETURN_CMD`co();   - returns when a user presses any of the above.

    `co(15,?);DO_INPUT_ADV`co();    - causes the tab to advance when an input is entered.
                      This bit makes forms that contain a lot of input much
                      easier to work, as it is not necessary to <Enter> on
                      each input to begin the entry.  In addition the user
                      will be able to use the <Tab>, <Up> and <Down> keys
                      or the mouse to move around the input fields while
                      actually in "edit input" mode.

    NOTE:  Any of the `co(15,?);DO_RETURN_X`co(); dialog defines can be or'ed together to
    combine dialog functionality.  For example, if you wish do_dialog to
    not process the Tab key, but rather return it to you, and return all
    events not processed, you would use `co(15,?);DO_RETURN_EVENT | DO_RETURN_TAB`co();.
    Or if you wish do_dialog to just do normal processing, you could use
    `co(15,?);DO_NORMAL`co();.  For a data entry form type dialog, just use `co(15,?);DO_INPUT_ADV`co();.
    As an extreme example, to make do_dialog return only when the arrow
    cursor keys are pressed, the Enter key, the Tab key, and any other
    event that is not an event that do_dialog will act upon, use
    `co(15,?);DO_RETURN_EVENT | DO_RETURN_ARROW | DO_RETURN_TAB | DO_RETURN_ENTER`co();.

Usage:
  TUI tui, TUI *tuip = &tui;
  
  draw_dialog(tuip, HELP_DLG);
  switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
	{
		...
	}
  erase_dialog(tuip, HELP_DPG);

`co(15,?);/// load_tui`co();   `keyword(source,[T_LOAD.C]~load_tui);
  Loads a TUI from disk.

Prototype:
	int load_tui( TUI *tuip, char *fname );

Parameters:
`co(11,?);  TUI  *tuip`co();
    A pointer to a TUI structure.                             
`co(11,?);  char *fname`co();
    The filename to load.
    
Usage:
  TUI tui, TUI *tuip = &tui;
  
  load_tui(tuip, "help.tui");
  init_tui(tuip);
  draw_dialog(tuip, HELP_DLG);
  switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  {
  	...
  }
  erase_dialog(tuip, HELP_DPG);
  end_tui(tuip);
  free_tui(tuip);

`co(15,?);/// save_tui`co();   `keyword(source,[T_SAVE.C]~save_tui);
  Saves a TUI to disk.

Prototype:
	int save_tui( TUI *tuip, char *fname );

Parameters:
`co(11,?);  TUI  *tuip`co();
    A pointer to a TUI structure.                             
`co(11,?);  char *fname`co();
    The filename to save.
    
Usage:
  TUI tui, TUI *tuip = &tui;
  
  load_tui(tuip, "help.tui");
  init_tui(tuip);
  /* modify buttons, positions, colors, etc */
  draw_dialog(tuip, HELP_DLG);
  switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  {
  	...
  }
  erase_dialog(tuip, HELP_DPG);
  save_tui(tuip, "help.tui");
  end_tui(tuip);
  free_tui(tuip);

`co(15,?);/// init_tui`co();   `keyword(source,[T_INIT.C]~init_tui */);
	  Initializes a TUI after it has been loaded or registered. This routine
	initializes the video mode and mouse and creates a full-screen background
	window.  This is the complement of `keyword(end_tui,/// end_tui);.

Prototype:
	int init_tui( TUI *tuip );

Parameters:
`co(11,?);  TUI *tuip`co();
    A pointer to a TUI structure.                             
    
Usage:
  TUI tui, TUI *tuip = &tui;
  
  load_tui(tuip, "help.tui");
  init_tui(tuip);
  draw_dialog(tuip, HELP_DLG);
  switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  {
  	...
  }
  erase_dialog(tuip, HELP_DPG);
  end_tui(tuip);
  free_tui(tuip);

`co(15,?);/// register_xxxx_tui`co();
	  Is used when a linkable TUI file is used instead of a disk loaded TUI.
	The dialog editor will generate a source file with a function named
	register_xxxx_tui where xxxx is the name of the TUI in question.  All you
	need to do is include this file in your project and call the function.
	This method prevents users from modifying the TUIs or deleting the TUI
	files accidently.

Prototype:
	int register_xxxx_tui( TUI *tuip );

Parameters:
`co(11,?);  TUI *tuip`co();
    A pointer to a TUI structure.  It will be filled out with the
    information in the linked TUI.

Usage:
  TUI tui, TUI *tuip = &tui;
  
  register_help_tui(tuip);
  init_tui(tuip);
  draw_dialog(tuip, HELP_DLG);
  switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  {
  	...
  }
  erase_dialog(tuip, HELP_DPG);
  end_tui(tuip);
  free_tui(tuip);

`co(15,?);/// end_tui`co();   `keyword(source,[T_INIT.C]~end_tui);
	  Ends a TUI, removes the full screen window and restores the video and
	mouse modes.  This is the complement of `keyword(init_tui,/// init_tui);.

Prototype:
	int end_tui( TUI *tuip );

Parameters:
`co(11,?);  TUI *tuip`co();
    A pointer to a TUI structure.                             
    
Usage:
  TUI tui, TUI *tuip = &tui;
  
  load_tui(tuip, "help.tui");
  init_tui(tuip);
  draw_dialog(tuip, HELP_DLG);
  switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  {
  	...
  }
  erase_dialog(tuip, HELP_DPG);
  end_tui(tuip);

`co(15,?);/// free_tui`co();   `keyword(source,[T_BASE.C]~free_tui);
	  Frees all objects within a TUI.  This function should be called when all
	operations with a TUI are complete.

Prototype:
	int free_tui( TUI *tuip );

Parameters:
`co(11,?);  TUI *tuip`co();
    A pointer to a TUI structure.                             
    
Usage:
  TUI tui, TUI *tuip = &tui;
  
  load_tui(tuip, "help.tui");
  init_tui(tuip);
  draw_dialog(tuip, HELP_DLG);
  switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  {
  	...
  }
  erase_dialog(tuip, HELP_DPG);
  end_tui(tuip);
  free_tui(tuip);

`co(15,?);/// set_slider`co();   `keyword(source,[T_UTIL.C]~set_slider);
	  Sets the slider variables.  A slider can range from 0 to total-1.  The
	arrow incs/decs by 1, a page incs/decs by page_amt, and sliding the grab
	box adjusts the position between 0 and total-1. Be sure to use long
	variables here or unexpected results will occur!

Prototype:
	set_slider( TUI *tuip, int inx, long position, long page_amt, long total );

Parameters:
`co(11,?);  TUI *tuip`co();
    A pointer to a TUI structure.                             
`co(11,?);  int  inx`co();
    The index into the TUI for this dialog object. (Use #define name).
`co(11,?);  long position`co();
    The initial offset of the slider (be sure to use long ints). 
`co(11,?);  long page_amt`co();
    The amount the slider incs/decs when paged (be sure to use long ints).
`co(11,?);  long total`co();
    The largest value - 1 the slider can have (be sure to use long ints). 
    
Usage:
  TUI tui, TUI *tuip = &tui;
  
  load_tui(tuip, "help.tui");
  init_tui(tuip);
  draw_dialog(tuip, HELP_DLG);
  switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  {
  	...
  }
  erase_dialog(tuip, HELP_DPG);
  end_tui(tuip);
  free_tui(tuip);

`co(15,?);/// file_selected`co();   `keyword(source,[T_FSEL.C]~file_selected);
	  Pulls up InTUItion's file selector and waits for the user to select a
	file.  The function will return 1 if a file was selected, or 0 if the
	selection was cancelled.  If a file was selected, the function will fill
	out the strings passed with information about the path and filename.

Prototype:
	file_selected(char *wildcard, char *path, char *filename, char *fullname);

Parameters:
`co(11,?);  char *wildcard`co();
    The initial wildcard to use.  For example, to use the file selector
    to select a "C" file, pass a wildcard of "*.C";
`co(11,?);  char *path`co();
    The default path to show.  If you wish, just pass a null string
    and the function will fill it out with the current path.
`co(11,?);  char *filename`co();
    The default filename.  Simply pass a null string, or if you wish
    pass a default filename.
`co(11,?);  char *fullname`co();
    This final parameter is what makes the file selector so easy to use.
    It is simply the drive, path and filename put together, ready for
    use in a file i/o function (like open).  This keeps you from having
    to concatenate the returned path and filename yourself.
    
Usage:
  WINDOW *wnp;
  char path[81], filename[13], fullname[81];  
  
  if ( file_selected("*.c", path, filename, fullname) )
  {
    mv_cs(0, 0, wnp);
    wn_printf(wnp, "The filename is <%s>, fullname <%s>",filename, fullname);
  }

`co(15,?);/// tui_help`co();   `keyword(source,[T_HELP.C]~tui_help);
	  Pulls up InTUItion's linkable help engine, and allows the user to browse
	through the help.  This is sometimes preferable over using the stand alone
	ENQHELP.EXE help engine.  Parameters to this function allow you to specify
	size, position, startup file, optional search string, and more.  Refer to
	the help engine documentation for information on how to create your own
	help files.

Prototype:
	tui_help( int sx, int sy, int ex, int ey, char *fname,
						char *search_str, int mode );

Parameters:
`co(11,?);  int sx, sy, ex, ey`co();
    The coordinates of the top-left and bottom-right corners of the help
    window.  These parameters allow you to change placement and size of
    the window.
`co(11,?);  char *fname`co();
    The default file to show.
`co(11,?);  char *search_str`co();
    The initial search string.  This parameter is what makes the help
    engine context-sensitive.  Just use "" if you wish to begin at the
    start of the file.
`co(11,?);  int mode`co();
    This is the chain mode, which tells the engine that if the search
    ends up on a hypertext keyword, to press <Enter> for the user.  This
    allows the engine to "chain" until the desired topic is reached,
    even across multiple files.
    
Usage:
  tui_help(1, 1, 79, 24, "SOURCE.C", "", 0);
  /* get the file SOURCE.C, and place the cursor at the top line */

  tui_help(1, 1, 79, 24, "MYFILE.HLP", "Introduction", 1);
  /* get the file MYFILE.HLP, search for the text "Introduction", and if
     it is a keyword <Enter> on it */
